X11 rust bindings.
This library allows to interact with an X11 server from rust code. A connection to an X11
server is represented by an implementation of the `Connection` trait.
The client can interact with the server by sending requests. The server can answer requests and
can also generate events.
The examples that come with this library might be a good starting point for new users.
# Getting started with X11
X11 is a big protocol. I would claim that most of it is not actually that complicated, but it
is still difficult to get into it. A good starting point might be some [libxcb
tutorial](https://www.x.org/releases/X11R7.7/doc/libxcb/tutorial/index.html). This tutorial
was adapted in this crate [as an
example](https://github.com/psychon/x11rb/blob/master/x11rb/examples/tutorial.rs). A more in-depth
look at the X11 protocol can be gained from the [protocol reference
manual](https://www.x.org/releases/X11R7.6/doc/xproto/x11protocol.html), but this requires some
existing basic understanding of X11. If you want to figure out what some specific request does,
be sure to look it up in the specification!
Most extensions can be understood by reading their specification. Most of them can be found
[here](https://www.x.org/releases/current/doc/index.html#protocol). For example, [the
specification of Composite
0.4](https://www.x.org/releases/X11R7.5/doc/compositeproto/compositeproto.txt) consists of
about six pages of text.
The notable exception is the X keyboard extension, which is documented in a [PDF file with 168
pages](https://www.x.org/releases/current/doc/kbproto/xkbproto.pdf) which I am never going to
read completely.
# Getting started with x11rb
Most code in this code is automatically generated from an XML description of the protocol. This
is the same approach as taken by [libxcb](https://xcb.freedesktop.org/) (and in fact this uses
the same XML description). This means that if you know your way around X11, most things should
be obvious to you.
For example, here is how to create a new window with x11rb:
```no_run
use x11rb::connection::Connection;
use x11rb::errors::ReplyOrIdError;
use x11rb::protocol::xproto::*;
use x11rb::COPY_DEPTH_FROM_PARENT;
fn main() -> Result<(), Box> {
let (conn, screen_num) = x11rb::connect(None).unwrap();
let screen = &conn.setup().roots[screen_num];
let win_id = conn.generate_id()?;
conn.create_window(
COPY_DEPTH_FROM_PARENT,
win_id,
screen.root,
0,
0,
100,
100,
0,
WindowClass::INPUT_OUTPUT,
0,
&CreateWindowAux::new().background_pixel(screen.white_pixel),
)?;
conn.map_window(win_id)?;
conn.flush();
loop {
println!("Event: {:?}", conn.wait_for_event()?);
}
}
```
More examples can be found in the
[examples](https://github.com/psychon/x11rb/tree/master/examples) directory.
## Feature flags
This crate uses [feature
flags](https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section) to reduce
the amount of compiled code. There are two kinds of feature flags available:
* Feature flags for specific X11 extensions
* Feature flags for additional functionality
### Feature flags for specific X11 extensions
By default, only the core X11 protocol and X11 extensions that are
needed internally are enabled. Further extensions need to be explicitly enabled via their
feature flag:
`composite`, `damage`, `dpms`, `dri2`, `dri3`, `glx`, `present`, `randr`, `record`, `render`,
`res`, `screensaver`, `shape`, `shm`, `sync`, `xevie`, `xf86dri`, `xf86vidmode`, `xfixes`,
`xinerama`, `xinput`, `xkb`, `xprint`, `xselinux`, `xtest`, `xv`, `xvmc`.
If you want to take the "I do not want to think about this"-approach, you can enable the
`all-extensions` feature to just enable, well, all extensions.
### Feature flags for additional functionality
Additionally, the following flags exist:
* `allow-unsafe-code`: Enable features that require `unsafe`. Without this flag,
`x11rb::xcb_ffi::XCBConnection` and some support code for it are unavailable.
* `cursor`: Enable the code in [crate::cursor] for loading cursor files.
* `resource_manager`: Enable the code in [crate::resource_manager] for loading and querying the
X11 resource database.
* `image`: Enable the code in [crate::image] for working with pixel image data.
* `dl-libxcb`: Enabling this feature will prevent from libxcb being linked to the
resulting executable. Instead libxcb will be dynamically loaded at runtime.
This feature adds the [`crate::xcb_ffi::load_libxcb`] function, that allows to load
libxcb and check for success or failure.
# Integrating x11rb with an Event Loop
The [event_loop_integration](event_loop_integration/index.html) module contains some hints for
integrating x11rb with an event loop as doc comments.